Please address the comments from this code review:

## Overall Comments
- Base64Encoder.encode now advertises support for bytes and Iterable[int], but it still unconditionally calls .encode('utf-8') on any non-bytearray input, which will fail for bytes/iterables and also treats bytes differently from bytearray; consider normalizing input types explicitly (e.g., separate branches for str, bytes/bytearray/memoryview, and Iterable[int]).
- CRC32._crc32_core uses `isinstance(data, bytes | bytearray | memoryview)`, but `isinstance` does not accept PEP 604 unions at runtime; replace this with a tuple (e.g., `(bytes, bytearray, memoryview)`) to avoid a TypeError.
- RequestSignatureValidator.validate_cookie appears to have copy-pasted error messages mentioning 'payload' and 'payload keys', which is misleading for cookie validation; update these messages to refer to 'cookie' instead for clearer diagnostics.

## Individual Comments

### Comment 1
<location> `src/xhshow/utils/encoder.py:33-36` </location>
<code_context>
+        )

-    def encode(self, data_to_encode: str) -> str:
+    def encode(self, data_to_encode: bytes | str | Iterable[int]) -> str:
         """
         Encode a string using custom Base64 alphabet
</code_context>

<issue_to_address>
**issue (bug_risk):** The new `encode` signature and implementation are inconsistent and will break for `bytes` and iterable inputs.

The new type hint allows `bytes` and `Iterable[int]`, but the implementation still assumes a `str` in the non-`bytearray` branch. `data_bytes = data_to_encode` followed by `data_to_encode.encode("utf-8")` will fail for `bytes` and generic iterables.

Either align the implementation with the annotation (e.g. normalize all inputs to `bytes` first, then encode/translate) or narrow the annotation back to `str` if wider support isn’t required.
</issue_to_address>

### Comment 2
<location> `src/xhshow/core/crc32_encrypt.py:66` </location>
<code_context>
+
+        c = cls.MASK32
+
+        if isinstance(data, bytes | bytearray | memoryview):
+            it = bytes(data)
+        elif isinstance(data, str):
</code_context>

<issue_to_address>
**issue (bug_risk):** The `isinstance` check using a `|` union will raise at runtime; it should use a tuple of types instead.

In CPython, `isinstance(obj, T1 | T2)` raises `TypeError: isinstance() argument 2 cannot be a union`. To keep the same behavior without a runtime error, this should be:

```python
if isinstance(data, (bytes, bytearray, memoryview)):
    it = bytes(data)
```
</issue_to_address>

### Comment 3
<location> `src/xhshow/utils/validators.py:80-90` </location>
<code_context>
         return payload

+    @staticmethod
+    def validate_cookie(cookie: Any) -> dict[str, Any] | str:
+        """Validate cookie parameter"""
+        if cookie is not None and not (isinstance(cookie, dict) or isinstance(cookie, str)):
+            raise TypeError(f"payload must be dict or None, got {type(cookie).__name__}")
+        # detect cookie dict validation
+        if cookie is not None and isinstance(cookie, dict):
+            for key in cookie.keys():
+                if not isinstance(key, str):
+                    raise TypeError(f"payload keys must be str, got {type(key).__name__} for key '{key}'")
+        return cookie
+
</code_context>

<issue_to_address>
**suggestion (bug_risk):** The error messages in `validate_cookie` reference `payload` instead of `cookie` and the accepted types don’t match the decorator usage.

The exceptions currently mention `payload` and refer to `dict or None`, which is misleading for a cookie validator and will confuse debugging.

There’s also a type mismatch: `validate_xs_common_params` can pass `None` (via the default), but `validate_cookie`’s return annotation doesn’t include `None`. Consider allowing `None` in the signature and aligning the error messages and types, e.g.:

```python
def validate_cookie(cookie: Any) -> dict[str, Any] | str | None:
    if cookie is not None and not isinstance(cookie, (dict, str)):
        raise TypeError(f"cookie must be dict, str, or None, got {type(cookie).__name__}")
    if isinstance(cookie, dict):
        for key in cookie.keys():
            if not isinstance(key, str):
                raise TypeError(
                    f"cookie keys must be str, got {type(key).__name__} for key '{key}'"
                )
    return cookie
```

```suggestion
    @staticmethod
    def validate_cookie(cookie: Any) -> dict[str, Any] | str | None:
        """Validate cookie parameter"""
        if cookie is not None and not isinstance(cookie, (dict, str)):
            raise TypeError(
                f"cookie must be dict, str, or None, got {type(cookie).__name__}"
            )
        if isinstance(cookie, dict):
            for key in cookie.keys():
                if not isinstance(key, str):
                    raise TypeError(
                        f"cookie keys must be str, got {type(key).__name__} for key '{key}'"
                    )
        return cookie
```
</issue_to_address>

### Comment 4
<location> `src/xhshow/utils/validators.py:213-222` </location>
<code_context>
     return wrapper  # type: ignore
+
+
+def validate_xs_common_params(func: F) -> F:  # type: ignore[misc]  # noqa: UP047
+    """
+    Parameter validation decorator for the `sign_xsc` method.
+
+    This wrapper normalizes and validates the arguments before delegating to
+    the underlying signing implementation.
+
+    Args:
+        func: Method to be decorated.
+
+    Returns:
+        Wrapped method with validated parameters.
+    """
+
+    @wraps(func)
+    def wrapper(
+        self,
+        cookie_dict: dict[str, Any] | None = None,
+    ) -> str:
+        validator = RequestSignatureValidator()
</code_context>

<issue_to_address>
**issue (bug_risk):** `validate_xs_common_params` changes the `sign_xsc` signature and allows `None`, which will break in the downstream implementation.

The wrapper currently changes the contract of `sign_xsc` from `dict[str, Any] | str` to `dict[str, Any] | None` and drops the `str` case.

This causes two problems:
1. Callers passing a cookie string are no longer supported (or the types are wrong), since `validate_cookie` doesn’t accept `str | None` as written.
2. When `cookie_dict` is `None`, `None` propagates into `sign_xsc` → `_parse_cookies` → `XsCommonSigner.sign`, which expects a `dict` and does `cookie_dict["a1"]`, leading to a runtime `TypeError` instead of consistent validation errors.

To fix this, keep the wrapper signature aligned with `sign_xsc` and ensure `validate_cookie` supports `str` and rejects `None` for required parameters:

```python
def wrapper(self, cookie_dict: dict[str, Any] | str) -> str:
    validator = RequestSignatureValidator()
    validated_cookie = validator.validate_cookie(cookie_dict)
    if validated_cookie is None:
        raise ValueError("cookie_dict is required")
    return func(self, validated_cookie)
```
</issue_to_address>

### Comment 5
<location> `tests/test_crypto.py:529` </location>
<code_context>
+        )
+
+        assert isinstance(headers, dict)
+        assert "x-s" in headers
+        assert "x-s-common" in headers
+        assert "x-t" in headers
</code_context>

<issue_to_address>
**issue (testing):** Tests expect `x-s` in `sign_headers` output but implementation currently only returns `x-s-common`

The implementation of `Xhshow.sign_headers` now omits `"x-s"` and only returns `"x-s-common"`, `"x-t"`, `"x-b3-traceid"`, and `"x-xray-traceid"`, but this and other tests still assert `"x-s"` and its prefix. Please decide what the contract of `sign_headers*` should be and update either the implementation (to re‑expose `"x-s"`) or the tests (to stop asserting it) so they are consistent.
</issue_to_address>

### Comment 6
<location> `tests/test_crypto.py:584` </location>
<code_context>
+        )
+
+        assert isinstance(headers, dict)
+        assert all(k in headers for k in ["x-s", "x-s-common", "x-t", "x-b3-traceid", "x-xray-traceid"])
+        assert headers["x-s"].startswith("XYS_")
+        assert len(headers["x-s-common"]) > 0
</code_context>

<issue_to_address>
**issue (testing):** `sign_headers_get`/`sign_headers_post` tests still assert presence and format of `x-s` despite it being removed from the headers dict

These tests still expect `"x-s"` to be present and to start with `"XYS_"`, but `client.sign_headers` no longer returns that header. Once the expected header set is confirmed, please update them to only assert keys that are part of the public API. If `x-s` is no longer returned, remove the `XYS_` prefix assertion here or move it into a test that directly targets the lower-level `sign_xs*` helpers.
</issue_to_address>

### Comment 7
<location> `tests/test_cookie_parsing.py:214` </location>
<code_context>
+        )
+
+        assert isinstance(headers, dict)
+        assert "x-s" in headers
+        assert "x-s-common" in headers
+        assert "x-t" in headers
</code_context>

<issue_to_address>
**issue (testing):** New cookie/header tests hard-code `x-s` in the header set, which conflicts with the current implementation

These tests currently assert that `"x-s"` is present in `sign_headers*` results and sometimes that it starts with `"XYS_"`, but this PR changes `sign_headers` to return `x-s-common` (and trace IDs) without `x-s`. Please align the expectations with the intended API:

- If `sign_headers*` should return both `x-s` and `x-s-common`, restore `x-s` in the implementation.
- If only `x-s-common` is public, drop the `x-s` assertions here and move any `x-s` format checks into lower-level signing tests.
</issue_to_address>

### Comment 8
<location> `tests/test_cookie_parsing.py:135-96` </location>
<code_context>
+        with pytest.raises(KeyError, match="a1"):
+            self.client.sign_xs_common(cookies)
+
+    def test_sign_xsc_alias(self):
+        """测试 sign_xsc 别名方法"""
+        cookies = {
+            "a1": "test_a1_value",
+            "web_session": "test_session",
+        }
+
+        result = self.client.sign_xsc(cookies)
+
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+
</code_context>

<issue_to_address>
**suggestion (testing):** Add negative tests for `sign_xsc` / `validate_xs_common_params` to cover type and value validation

Since `sign_xsc` is decorated with `@validate_xs_common_params` (which calls `RequestSignatureValidator.validate_cookie`), the current test only covers the valid dict case. Please add negative tests that:

- Pass an unsupported type (e.g. list/int) as `cookie_dict` and assert a `TypeError` with the expected message.
- Use a cookie dict with non-string keys to cover the key-type validation path.
- Optionally, pass `None` (depending on the intended contract) and assert the expected behaviour.

This will exercise the validator’s error handling and lock in the parameter contract for `sign_xsc`.

Suggested implementation:

```python
+    def test_sign_xsc_alias(self):
+        """测试 sign_xsc 别名方法"""
+        cookies = {
+            "a1": "test_a1_value",
+            "web_session": "test_session",
+        }
+
+        result = self.client.sign_xsc(cookies)
+
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    def test_sign_xsc_invalid_type(self):
+        """测试 sign_xsc 传入非 dict 类型参数时抛出异常"""
+        # list 作为参数
+        with pytest.raises(TypeError, match="cookie_dict"):
+            self.client.sign_xsc(["not", "a", "dict"])  # type: ignore[arg-type]
+
+        # int 作为参数
+        with pytest.raises(TypeError, match="cookie_dict"):
+            self.client.sign_xsc(123)  # type: ignore[arg-type]
+
+    def test_sign_xsc_non_string_keys(self):
+        """测试 sign_xsc 传入非字符串 key 的 cookie 时抛出异常"""
+        cookies = {
+            "a1": "test_a1_value",
+            "web_session": "test_session",
+            123: "value_with_int_key",  # 非字符串 key
+        }
+
+        with pytest.raises(TypeError, match="key"):
+            self.client.sign_xsc(cookies)  # type: ignore[dict-item]
+
+    def test_sign_xsc_none_cookie_dict(self):
+        """测试 sign_xsc 传入 None 时的参数校验行为"""
+        with pytest.raises(TypeError, match="cookie_dict"):
+            self.client.sign_xsc(None)  # type: ignore[arg-type]
+
+

```

These tests assume that `@validate_xs_common_params` / `RequestSignatureValidator.validate_cookie`:
1. Raise `TypeError` when `cookie_dict` is not a `dict` (list/int/None case) and that the error message contains `cookie_dict`.
2. Raise `TypeError` for non-string keys with an error message containing `key`.

If the actual validator uses different exception types or messages, adjust:
- The exception class in `pytest.raises(...)`.
- The `match` patterns to align with the real error messages.

No other code changes should be required if `self.client.sign_xsc` is already available in the test class.
</issue_to_address>

### Comment 9
<location> `tests/test_cookie_parsing.py:148-157` </location>
<code_context>
+class TestXsCommonSigner:
</code_context>

<issue_to_address>
**suggestion (testing):** Strengthen `XsCommonSigner` tests with a fixed-vector or structural assertion that covers the b1/Base64 regression

Current tests only verify that the output is non-empty and that missing `a1` raises `KeyError`, which doesn’t validate the corrected byte-based Base64 behaviour for `b1`.

To better cover this regression, please add a deterministic test that:
- Uses a fixed cookie dict and `CryptoConfig` (with deterministic fingerprint),
- Produces `b1` via `FingerprintGenerator.generate_b1()` or `XsCommonSigner`, and
- Asserts that `b1` (or `x-s-common`) matches a known-good value or prefix from reference browser/VM output (e.g. starts with `"I38r"`).

Suggested implementation:

```python
class TestXsCommonSigner:
    """测试 XsCommonSigner 类"""

    def setup_method(self):
        self.signer = XsCommonSigner()

    def test_sign_with_dict_only(self):
        """测试只接受字典参数"""
        cookies = {
            "a1": "test_a1_value",
            "web_session": "test_session",
        }

        # 基本行为：返回非空字符串
        result = self.signer.sign(cookies)
        assert isinstance(result, str)
        assert result

    def test_b1_base64_regression_vector(self):
        """使用固定向量验证 b1/Base64 行为，防止回归"""
        cookies = {
            "a1": "fixed_a1_value",
            "web_session": "fixed_session_value",
        }

        # 使用固定的 CryptoConfig 以获得确定性的指纹
        crypto_config = CryptoConfig(
            fingerprint="fixed_fingerprint_for_test",
        )

        fp_gen = FingerprintGenerator(crypto_config=crypto_config)

        # 直接生成 b1，确保是稳定的 Base64 字节编码
        b1 = fp_gen.generate_b1(cookies)
        assert isinstance(b1, str)
        assert b1  # 非空

        # 结构性断言：b1 必须以已知前缀开头（来自参考浏览器/VM 输出）
        # 注意：前缀 "I38r" 需要根据实际参考输出进行同步
        assert b1.startswith("I38r")

        # 通过 XsCommonSigner 生成 x-s-common 头部，应与 b1 行为一致
        x_s_common = self.signer.sign(cookies=cookies, crypto_config=crypto_config)
        assert isinstance(x_s_common, str)
        assert x_s_common
        assert x_s_common.startswith("I38r")

```

1. 在 `tests/test_cookie_parsing.py` 顶部增加正确的导入（根据实际模块路径调整）：
   ```python
   from your_module_path import CryptoConfig, FingerprintGenerator
   ```
   或者如果它们在不同模块中，请分别导入。

2. 确认 `XsCommonSigner` 的 API：
   - 如果当前签名方法不是 `sign`，而是例如 `sign_xsc` 或其他名字，请将
     ```python
     result = self.signer.sign(cookies)
     x_s_common = self.signer.sign(cookies=cookies, crypto_config=crypto_config)
     ```
     替换为实际的方法名和参数签名。

3. 如果 `CryptoConfig` 构造函数需要额外参数（例如密钥、盐值等），为测试构造一个完全确定性的配置（固定密钥/盐），并在 `test_b1_base64_regression_vector` 中补全这些参数。

4. `FingerprintGenerator` 的初始化和 `generate_b1` 调用可能需要不同的参数名或额外上下文：
   - 将
     ```python
     fp_gen = FingerprintGenerator(crypto_config=crypto_config)
     b1 = fp_gen.generate_b1(cookies)
     ```
     调整为当前项目中实际的初始化方式与方法签名。

5. `"I38r"` 仅是示例前缀，请从参考浏览器/VM 输出中获取真实的 `b1` 值或前缀，并更新断言：
   ```python
   assert b1.startswith("<真实前缀>")
   assert x_s_common.startswith("<真实前缀>")
   ```

6. 如项目中已有 pytest fixture 提供 `CryptoConfig` 或 `FingerprintGenerator`（例如 `crypto_config`、`fingerprint_generator`），可以将测试改写为使用这些 fixture，而不是在测试中直接构造实例，以保持与现有测试风格一致。
</issue_to_address>

### Comment 10
<location> `README.md:193` </location>
<code_context>
+cookie_string = "a1=your_a1_value; web_session=your_web_session; webId=your_web_id"
+xs_common = client.sign_xsc(cookie_dict=cookie_string)
+
+# 使用在请求中
+headers = {
+    "x-s-common": xs_common,
</code_context>

<issue_to_address>
**suggestion (typo):** “使用在请求中”建议调整为更自然的表达，如“在请求中使用”。

这句注释略显别扭，建议改为“# 在请求中使用”，更符合中文表达习惯。

```suggestion
# 在请求中使用
```
</issue_to_address>